The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / telecomm / fnordadl / fn132man.zoo / chapter.09 < prev next >

Wrap

Text File | 1991-09-02 | 17.6 KB | 417 lines

Chapter 9: Doors 126 9 Doors The Fnordadel __door__ mechanism allows the Sysop to provide access to external programs from within the BBS, in a controllable fashion. This allows things like online games, additional file transfer protocols, or whatever you feel like. This chapter describes the door mechanism. 9.1 Defining Doors Doors are defined in the file `ctdldoor.sys', which lives in your #sysdir. It is a simple ASCII text file, editable with any text editor or word processor that will save in ASCII. It is read into memory by citadel when it runs; if you change the file somehow while Fnordadel is running, you'll have to [Q]uit from the BBS and re-run citadel to make the change take effect. 9.1.1 Format of ctdldoor.sys The `ctdldoor.sys' file consists of any number of lines (each of which defines a separate door), in the following format: <door> <mode> <program-name> [command tail] [#comment] The fields should be separated by white-space (i.e., spaces or tabs). The meanings of the individual fields are as follows: door The name that Fnordadel will use to refer to this door. It must be unique among all the doors you have defined. mode The set of permissions/restrictions on this door. It consists of a string of any of these characters (although some combinations don't make sense): `u' Anyone may use this door. `a' Only Aides, Co-Sysops and the Sysop may use this door. `s' Only Co-Sysops and the Sysop may use this door. `z' Only the Sysop may use this door (that's you usually, but it could also be any Sysop logged in at the system console, or who has supplied the system password to get into the Sysop menu). `c' Only users on the system console may use this door. `m' Only users on the modem may use this door. `d' This door must be executed from within a directory room. Chapter 9: Doors 127 `r' For `d' above; the directory must be readable. `w' For `d' above; the directory must be writable. `t' The user may provide a command tail for this command. `n' Pass the user name to this command as part of the command tail (as the end of the tail). `x' This door is a ``system'' door. See Section 9.3.1 [System doors], page 130. `v' This door is an ``archiver'' door, defining a file archiver which Fnordadel will use to read the table of contents of archive files. See Section 9.3.2 [Archiver doors], page 130. `p' This door is a ``protocol'' door, defining a file transfer protocol. See Section 9.3.3 [Protocol doors], page 131. `h' This door will be executed from the BBS home directory (i.e. where ctdlcnfg.sys lives). Normally, a door executed in a directory room will be run from that room's directory. Some doors don't like that, so this mode can be set to correct things. If the `l' mode is also present, it will override this mode. `i' If present, this must be the last mode. The rest of the mode string is the name of a room to which the door will be linked. The door will only show up in the `!?' list in that room, and will only be runnable in that room. If the room name contains spaces, replace them with `_' in the door declaration. If a mode string ended with `iFoo_blort', for example, this particular door is tied to room Foo blort. If Foo blort is a directory room, Fnordadel will make the room's directory the working directory for the door when it is run. The `i' mode can't be used with the `l' mode, described next. `l' If present, this must be the last mode. The rest of the mode string is the directory to which this command will be linked. If a mode string ends with `lc:\bin', for example, Fnordadel will make `c:\bin' the current working directory when running this command. The `l' mode can't be used with the `i' mode, described above. If used with the `h' mode, `l' takes precedence. program-name The full pathname, including the filename extension, of the program attached to this door. Chapter 9: Doors 128 command tail The optional command tail to pass to this door upon execution. If the door allows a user-supplied command tail, it will be appended to this command tail, and user names (mode character `n') are appended after everything else. comment Also optional. This field must be preceded by a `#'. It allows you to put in a short description of what the door does, which users will see when they hit `!?'. 9.1.2 Example door definitions Here are some sample door definitions, some of which you may want to use on your system: clog u e:\citutil\clog.tos -t # 3-column log reader uclog s e:\citutil\clog.tos -p # log reader for Sysop rz udrt c:\bin\rz.ttp # zmodem download ez udwt c:\bin\sz.ttp # zmodem upload The first example provides a quick way for users to get an up-to-the-minute quickie listing of the user log; it will print out the names only, in three-column format. (See `clog.man' for more on clog.) The second example is for Sysop and Co-Sysop use only (note the mode string of `s'). It runs clog and passes it the argument `-p' (which enables the printing of passwords). You'd use this if someone forgot their password and you wanted to find out what it was (be careful of hackers, though). The third example implements Zmodem downloads via the external program `rz.ttp', which is kept in `c:\bin'. It passes no command tail of its own, but it does allow the user to pass a tail in, so he can specify which file(s) he wants to download. The fourth example implements Zmodem uploads. Notice that the mode string consists of `udwt'; the `w' means that this door is only usable in rooms which allow uploads. Makes sense, right? 9.1.3 Notes o In any directory room, the ``current directory'' (for the purposes of the door program) is always set to be the directory attached to the room, unless you use the link mode `l' to specify another directory. o User-supplied command tails (enabled with `t' in the mode string) will be scanned for occurences of `\' and `:' characters, and these will be removed. This is to stop an unscrupulous user from passing full pathnames to, say, a file transfer program and gaining access to private information; users will only be able to access information to which they have normal Citadel access (by being in a directory room). Chapter 9: Doors 129 o If you're running an online game or something which requires that it be pointed at a specific directory (so it can access data files or whatever), use the mode `l<dirname>'. This is the most common problem in getting many doors to run. o If you want to restrict a door to be used only by certain users, make a private or invitation-only room, and link the door to that room using the `i' mode. If the door program in question also needs to be linked to a directory in order to run properly, make the room a directory room pointing at the needed directory. o The syntax of door definitions may be checked by using the utility program ckdoor. See `ckdoor.man' for details of its usage. 9.2 The User Interface A door command, from the user's point of view, is very simple: !door [command-tail] Simply type a `!', followed by the name of the door; if the door allows or requires a command tail to be passed in, as in the example door `rz' from Section 9.1.2 [Example doors], page 128, then it should be separated from the door name by a space, and the remainder of the door command is taken to be the command tail. So, using `rz' to download the files `foo', `bar', and `blort', the user would simply say: !rz foo bar blort at the room prompt. The program `c:\bin\rz.ttp' will be run, and `foo bar blort' will be passed to it as a command tail. Easy, huh? Typing `!?' will print out a list of doors accessible from the current room by the current user. So you'll notice that the list may vary, depending on the type of user logged in (Sysop, Co-Sysop, Aide or normal user), and on the room or type of room the user is in (directory or normal). Doors that specify `sd', for example, in the mode string will not be listed when an Aide does `!?' in a non-directory room. Also, overall door access can be controlled by the door privilege flag in each user's account, and the #alldoor flag in `ctdlcnfg.sys'. See Section 5.2 [User Status Commands], page 80, for more information, as well as the #alldoor description in `ctdlcnfg.doc', and the flipbits documentation in `flipbits.man'. Chapter 9: Doors 130 9.3 Special Kinds of Doors 9.3.1 System doors Doors with a mode of `x' are special __system__ doors. These doors currently are no different than doors with a mode of `z' (for use by the Sysop only), but that may change in the future. For now, these doors are intended to be ones that aren't run explicitly by any user, even the Sysop. There are three special doors that you will probably want to define as system doors: `login' (run automatically when any user logs in); `logout' (run automatically when any user logs out); and `newuser' (run automatically when a new user logs in the first time). Here are some examples: login x c:\bin\cookie.tos newuser nx d:\bbsprogs\survey.ttp The first example runs a cookie program (something that spits out a random witty quote) for every user that logs in. The second example runs a hypothetical survey program for each new caller, passing the user's name to the program (mode character `n'). Note that all of these special doors must have the exact name as given here (`login', `logout' or `newuser'). This implies that you can only have one door of each type. If you need more, you'll need to write yourself a custom program that calls, in turn, each of the other programs that you wish to be executed. 9.3.2 Archiver doors Doors with a mode of `v' are __archiver__ doors. These will usually not be called directly using the `!door' syntax, but indirectly, using the .R(ead) (archive-)H(eader) command. These doors enable users to view the contents of any archive file, even though the Fnordadel internal code only supports the .arc file type. Here's a couple of examples. In your `ctdlcnfg.sys' file, put: #archiver ZOO zootoc #archiver LZH lzhtoc In your `ctdldoor.sys' file, put: zootoc tdrv c:\bin\zoo.ttp v lzhtoc tdrv c:\bin\lharc102.ttp v Both doors take command tails (`t'), are usable only in readable directory rooms (`dr'), and are flagged as archiver doors (`v'). To use them, all a user needs to do is enter commands like `.RH foobar.zoo' and `.RH blort.lzh'. Chapter 9: Doors 131 9.3.3 Protocol doors Doors with a mode of `p' are __protocol__ doors. They are currently not used in any special way by the system, but a coming enhancement will allow them to function for file transfers sort of like archiver doors do for the `.RH' command. For example, suppose you defined a door like: rz tdrp c:\bin\rz.ttp Zmodem-download Then users could download files using the Zmodem transfer protocol by entering a command like `.RZFfoo.bar', which would echo like .Read Zmodem-download File foo.bar. Look for this in an upcoming release. 9.3.4 The shell door If you have a door which is named `shell', it will override the setting of the #shell variable in `ctdlcnfg.sys'. See `ctdlcnfg.doc'. This door is meant to be a program like command.tos, PCOMMAND, or gulam. Executing the `!shell' door is equivalent to executing the [O]utside command in the Sysop menu; see Section 5.1 [Sysop Special Functions], page 75. 9.3.5 Fnordadel as a door It is theoretically possible to run Fnordadel itself as a door! Unfortunately, this currently will not work if your main BBS software is also STadel or Fnordadel (we're working on it), although it should work from within fOrEm and others that support doors. To run Fnordadel as a door from another system, set it up as you would if you were running it stand-alone. Then create a door on your main system to change directory into your Fnordadel's home directory, and invoke it with the command: citadel +door When Fnordadel comes up, it will assume that a user is already connected. Thus, no modem commands or controls will be used. When the user terminates, Fnordadel will exit and return control to the calling program. You may supply other parameters to citadel if you wish, but do not use `+multi'. Also, you may need to avoid using `+line', since the status line may screw up your main system. 9.4 Notes and Caveats Chapter 9: Doors 132 9.5 Door Problems Getting doors to work can sometimes be a tricky thing, even if everything looks good and ckdoor doesn't complain about your `ctdldoor.sys' file. A common problem with programs used as doors is that they don't process command line parameters the same way Fnordadel does. Fnordadel passes parameters to all doors using the Atari-sanctioned ``ARGV'' method, which is used by Mark Williams C, Gnu C, and possibly other languages also. However, many languages do not use this method of handling command line parameters, and so won't work as Fnordadel doors. To get around this problem is not difficult, hopefully. We provide a utility program called doorwrap, whose only purpose is to take a parameter list from Fnordadel, convert it to a different form, and pass the result on to the *real* door program, which will hopefully be able to process the new format of the parameters. To use doorwrap, declare your door exactly as you normally would, but insert the full pathname of doorwrap immediately prior to the pathname of the real door program. Here's an example: Before: foobar ut c:\blort\foobar.tos -dv After: foobar ut c:\fnordbin\doorwrap.tos c:\blort\foobar.tos -dv For more information on doorwrap, see `doorwrap.man'. For other compatibility and support information, see Section 13.8 [Compatibilities], page 168, and Appendix A [Fnordadel Support], page 170. o If someone drops carrier while running a door, the door program (depending on whether it's been written to detect the loss of carrier) will probably be sitting waiting for the user to type something when the next call comes in; the next caller may well end up dumped right into the door where the last caller left off. Depending on the program, it may well be a Bad Thing. Be really careful of this problem when defining special doors like `login', `logout', and `newuser'. o Be careful when giving out access to things like shell programs and stuff; anything that gives the user access to your whole file system (and especially stuff like shells that gives them access to things like directory removal commands) is potentially hazardous to the health of your BBS and anything else accessible. o If you have people hogging a lot of system time using doors, there isn't much you can do about it other than turf the doors. However, you can set the #maxtime parameter in `ctdlcnfg.sys' to place some limits on users' abilities to monopolize your system. See `ctdlcnfg.doc' and Chapter 10 [Anti-Ruggie Measures], page 133, for details. o If you have problems with people using doors and screwing up events you have defined, see the #eventclosetime parameter in `ctdlcnfg.doc'. It lets you specify a cut-off time in minutes. If an event is that number of minutes (or less) away from happening, users won't be allowed to start any doors.